kodelyth-ecc 2.19.0 → 2.20.0

package/.cursor/skills/swift-concurrency-6-2/SKILL.md

@@ -1,216 +0,0 @@
----
-name: swift-concurrency-6-2
-description: Swift 6.2 Approachable Concurrency — single-threaded by default, @concurrent for explicit background offloading, isolated conformances for main actor types.
----
-
-# Swift 6.2 Approachable Concurrency
-
-Patterns for adopting Swift 6.2's concurrency model where code runs single-threaded by default and concurrency is introduced explicitly. Eliminates common data-race errors without sacrificing performance.
-
-## When to Activate
-
-- Migrating Swift 5.x or 6.0/6.1 projects to Swift 6.2
-- Resolving data-race safety compiler errors
-- Designing MainActor-based app architecture
-- Offloading CPU-intensive work to background threads
-- Implementing protocol conformances on MainActor-isolated types
-- Enabling Approachable Concurrency build settings in Xcode 26
-
-## Core Problem: Implicit Background Offloading
-
-In Swift 6.1 and earlier, async functions could be implicitly offloaded to background threads, causing data-race errors even in seemingly safe code:
-
-```swift
-// Swift 6.1: ERROR
-@MainActor
-final class StickerModel {
-    let photoProcessor = PhotoProcessor()
-
-    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
-        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
-
-        // Error: Sending 'self.photoProcessor' risks causing data races
-        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
-    }
-}
-```
-
-Swift 6.2 fixes this: async functions stay on the calling actor by default.
-
-```swift
-// Swift 6.2: OK — async stays on MainActor, no data race
-@MainActor
-final class StickerModel {
-    let photoProcessor = PhotoProcessor()
-
-    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
-        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
-        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
-    }
-}
-```
-
-## Core Pattern — Isolated Conformances
-
-MainActor types can now conform to non-isolated protocols safely:
-
-```swift
-protocol Exportable {
-    func export()
-}
-
-// Swift 6.1: ERROR — crosses into main actor-isolated code
-// Swift 6.2: OK with isolated conformance
-extension StickerModel: @MainActor Exportable {
-    func export() {
-        photoProcessor.exportAsPNG()
-    }
-}
-```
-
-The compiler ensures the conformance is only used on the main actor:
-
-```swift
-// OK — ImageExporter is also @MainActor
-@MainActor
-struct ImageExporter {
-    var items: [any Exportable]
-
-    mutating func add(_ item: StickerModel) {
-        items.append(item)  // Safe: same actor isolation
-    }
-}
-
-// ERROR — nonisolated context can't use MainActor conformance
-nonisolated struct ImageExporter {
-    var items: [any Exportable]
-
-    mutating func add(_ item: StickerModel) {
-        items.append(item)  // Error: Main actor-isolated conformance cannot be used here
-    }
-}
-```
-
-## Core Pattern — Global and Static Variables
-
-Protect global/static state with MainActor:
-
-```swift
-// Swift 6.1: ERROR — non-Sendable type may have shared mutable state
-final class StickerLibrary {
-    static let shared: StickerLibrary = .init()  // Error
-}
-
-// Fix: Annotate with @MainActor
-@MainActor
-final class StickerLibrary {
-    static let shared: StickerLibrary = .init()  // OK
-}
-```
-
-### MainActor Default Inference Mode
-
-Swift 6.2 introduces a mode where MainActor is inferred by default — no manual annotations needed:
-
-```swift
-// With MainActor default inference enabled:
-final class StickerLibrary {
-    static let shared: StickerLibrary = .init()  // Implicitly @MainActor
-}
-
-final class StickerModel {
-    let photoProcessor: PhotoProcessor
-    var selection: [PhotosPickerItem]  // Implicitly @MainActor
-}
-
-extension StickerModel: Exportable {  // Implicitly @MainActor conformance
-    func export() {
-        photoProcessor.exportAsPNG()
-    }
-}
-```
-
-This mode is opt-in and recommended for apps, scripts, and other executable targets.
-
-## Core Pattern — @concurrent for Background Work
-
-When you need actual parallelism, explicitly offload with `@concurrent`:
-
-> **Important:** This example requires Approachable Concurrency build settings — SE-0466 (MainActor default isolation) and SE-0461 (NonisolatedNonsendingByDefault). With these enabled, `extractSticker` stays on the caller's actor, making mutable state access safe. **Without these settings, this code has a data race** — the compiler will flag it.
-
-```swift
-nonisolated final class PhotoProcessor {
-    private var cachedStickers: [String: Sticker] = [:]
-
-    func extractSticker(data: Data, with id: String) async -> Sticker {
-        if let sticker = cachedStickers[id] {
-            return sticker
-        }
-
-        let sticker = await Self.extractSubject(from: data)
-        cachedStickers[id] = sticker
-        return sticker
-    }
-
-    // Offload expensive work to concurrent thread pool
-    @concurrent
-    static func extractSubject(from data: Data) async -> Sticker { /* ... */ }
-}
-
-// Callers must await
-let processor = PhotoProcessor()
-processedPhotos[item.id] = await processor.extractSticker(data: data, with: item.id)
-```
-
-To use `@concurrent`:
-1. Mark the containing type as `nonisolated`
-2. Add `@concurrent` to the function
-3. Add `async` if not already asynchronous
-4. Add `await` at call sites
-
-## Key Design Decisions
-
-| Decision | Rationale |
-|----------|-----------|
-| Single-threaded by default | Most natural code is data-race free; concurrency is opt-in |
-| Async stays on calling actor | Eliminates implicit offloading that caused data-race errors |
-| Isolated conformances | MainActor types can conform to protocols without unsafe workarounds |
-| `@concurrent` explicit opt-in | Background execution is a deliberate performance choice, not accidental |
-| MainActor default inference | Reduces boilerplate `@MainActor` annotations for app targets |
-| Opt-in adoption | Non-breaking migration path — enable features incrementally |
-
-## Migration Steps
-
-1. **Enable in Xcode**: Swift Compiler > Concurrency section in Build Settings
-2. **Enable in SPM**: Use `SwiftSettings` API in package manifest
-3. **Use migration tooling**: Automatic code changes via swift.org/migration
-4. **Start with MainActor defaults**: Enable inference mode for app targets
-5. **Add `@concurrent` where needed**: Profile first, then offload hot paths
-6. **Test thoroughly**: Data-race issues become compile-time errors
-
-## Best Practices
-
-- **Start on MainActor** — write single-threaded code first, optimize later
-- **Use `@concurrent` only for CPU-intensive work** — image processing, compression, complex computation
-- **Enable MainActor inference mode** for app targets that are mostly single-threaded
-- **Profile before offloading** — use Instruments to find actual bottlenecks
-- **Protect globals with MainActor** — global/static mutable state needs actor isolation
-- **Use isolated conformances** instead of `nonisolated` workarounds or `@Sendable` wrappers
-- **Migrate incrementally** — enable features one at a time in build settings
-
-## Anti-Patterns to Avoid
-
-- Applying `@concurrent` to every async function (most don't need background execution)
-- Using `nonisolated` to suppress compiler errors without understanding isolation
-- Keeping legacy `DispatchQueue` patterns when actors provide the same safety
-- Skipping `model.availability` checks in concurrency-related Foundation Models code
-- Fighting the compiler — if it reports a data race, the code has a real concurrency issue
-- Assuming all async code runs in the background (Swift 6.2 default: stays on calling actor)
-
-## When to Use
-
-- All new Swift 6.2+ projects (Approachable Concurrency is the recommended default)
-- Migrating existing apps from Swift 5.x or 6.0/6.1 concurrency
-- Resolving data-race safety compiler errors during Xcode 26 adoption
-- Building MainActor-centric app architectures (most UI apps)
-- Performance optimization — offloading specific heavy computations to background

package/.cursor/skills/swift-protocol-di-testing/SKILL.md

@@ -1,190 +0,0 @@
----
-name: swift-protocol-di-testing
-description: Protocol-based dependency injection for testable Swift code — mock file system, network, and external APIs using focused protocols and Swift Testing.
-origin: ECC
----
-
-# Swift Protocol-Based Dependency Injection for Testing
-
-Patterns for making Swift code testable by abstracting external dependencies (file system, network, iCloud) behind small, focused protocols. Enables deterministic tests without I/O.
-
-## When to Activate
-
-- Writing Swift code that accesses file system, network, or external APIs
-- Need to test error handling paths without triggering real failures
-- Building modules that work across environments (app, test, SwiftUI preview)
-- Designing testable architecture with Swift concurrency (actors, Sendable)
-
-## Core Pattern
-
-### 1. Define Small, Focused Protocols
-
-Each protocol handles exactly one external concern.
-
-```swift
-// File system access
-public protocol FileSystemProviding: Sendable {
-    func containerURL(for purpose: Purpose) -> URL?
-}
-
-// File read/write operations
-public protocol FileAccessorProviding: Sendable {
-    func read(from url: URL) throws -> Data
-    func write(_ data: Data, to url: URL) throws
-    func fileExists(at url: URL) -> Bool
-}
-
-// Bookmark storage (e.g., for sandboxed apps)
-public protocol BookmarkStorageProviding: Sendable {
-    func saveBookmark(_ data: Data, for key: String) throws
-    func loadBookmark(for key: String) throws -> Data?
-}
-```
-
-### 2. Create Default (Production) Implementations
-
-```swift
-public struct DefaultFileSystemProvider: FileSystemProviding {
-    public init() {}
-
-    public func containerURL(for purpose: Purpose) -> URL? {
-        FileManager.default.url(forUbiquityContainerIdentifier: nil)
-    }
-}
-
-public struct DefaultFileAccessor: FileAccessorProviding {
-    public init() {}
-
-    public func read(from url: URL) throws -> Data {
-        try Data(contentsOf: url)
-    }
-
-    public func write(_ data: Data, to url: URL) throws {
-        try data.write(to: url, options: .atomic)
-    }
-
-    public func fileExists(at url: URL) -> Bool {
-        FileManager.default.fileExists(atPath: url.path)
-    }
-}
-```
-
-### 3. Create Mock Implementations for Testing
-
-```swift
-public final class MockFileAccessor: FileAccessorProviding, @unchecked Sendable {
-    public var files: [URL: Data] = [:]
-    public var readError: Error?
-    public var writeError: Error?
-
-    public init() {}
-
-    public func read(from url: URL) throws -> Data {
-        if let error = readError { throw error }
-        guard let data = files[url] else {
-            throw CocoaError(.fileReadNoSuchFile)
-        }
-        return data
-    }
-
-    public func write(_ data: Data, to url: URL) throws {
-        if let error = writeError { throw error }
-        files[url] = data
-    }
-
-    public func fileExists(at url: URL) -> Bool {
-        files[url] != nil
-    }
-}
-```
-
-### 4. Inject Dependencies with Default Parameters
-
-Production code uses defaults; tests inject mocks.
-
-```swift
-public actor SyncManager {
-    private let fileSystem: FileSystemProviding
-    private let fileAccessor: FileAccessorProviding
-
-    public init(
-        fileSystem: FileSystemProviding = DefaultFileSystemProvider(),
-        fileAccessor: FileAccessorProviding = DefaultFileAccessor()
-    ) {
-        self.fileSystem = fileSystem
-        self.fileAccessor = fileAccessor
-    }
-
-    public func sync() async throws {
-        guard let containerURL = fileSystem.containerURL(for: .sync) else {
-            throw SyncError.containerNotAvailable
-        }
-        let data = try fileAccessor.read(
-            from: containerURL.appendingPathComponent("data.json")
-        )
-        // Process data...
-    }
-}
-```
-
-### 5. Write Tests with Swift Testing
-
-```swift
-import Testing
-
-@Test("Sync manager handles missing container")
-func testMissingContainer() async {
-    let mockFileSystem = MockFileSystemProvider(containerURL: nil)
-    let manager = SyncManager(fileSystem: mockFileSystem)
-
-    await #expect(throws: SyncError.containerNotAvailable) {
-        try await manager.sync()
-    }
-}
-
-@Test("Sync manager reads data correctly")
-func testReadData() async throws {
-    let mockFileAccessor = MockFileAccessor()
-    mockFileAccessor.files[testURL] = testData
-
-    let manager = SyncManager(fileAccessor: mockFileAccessor)
-    let result = try await manager.loadData()
-
-    #expect(result == expectedData)
-}
-
-@Test("Sync manager handles read errors gracefully")
-func testReadError() async {
-    let mockFileAccessor = MockFileAccessor()
-    mockFileAccessor.readError = CocoaError(.fileReadCorruptFile)
-
-    let manager = SyncManager(fileAccessor: mockFileAccessor)
-
-    await #expect(throws: SyncError.self) {
-        try await manager.sync()
-    }
-}
-```
-
-## Best Practices
-
-- **Single Responsibility**: Each protocol should handle one concern — don't create "god protocols" with many methods
-- **Sendable conformance**: Required when protocols are used across actor boundaries
-- **Default parameters**: Let production code use real implementations by default; only tests need to specify mocks
-- **Error simulation**: Design mocks with configurable error properties for testing failure paths
-- **Only mock boundaries**: Mock external dependencies (file system, network, APIs), not internal types
-
-## Anti-Patterns to Avoid
-
-- Creating a single large protocol that covers all external access
-- Mocking internal types that have no external dependencies
-- Using `#if DEBUG` conditionals instead of proper dependency injection
-- Forgetting `Sendable` conformance when used with actors
-- Over-engineering: if a type has no external dependencies, it doesn't need a protocol
-
-## When to Use
-
-- Any Swift code that touches file system, network, or external APIs
-- Testing error handling paths that are hard to trigger in real environments
-- Building modules that need to work in app, test, and SwiftUI preview contexts
-- Apps using Swift concurrency (actors, structured concurrency) that need testable architecture

package/.cursor/skills/swiftui-patterns/SKILL.md

@@ -1,259 +0,0 @@
----
-name: swiftui-patterns
-description: SwiftUI architecture patterns, state management with @Observable, view composition, navigation, performance optimization, and modern iOS/macOS UI best practices.
----
-
-# SwiftUI Patterns
-
-Modern SwiftUI patterns for building declarative, performant user interfaces on Apple platforms. Covers the Observation framework, view composition, type-safe navigation, and performance optimization.
-
-## When to Activate
-
-- Building SwiftUI views and managing state (`@State`, `@Observable`, `@Binding`)
-- Designing navigation flows with `NavigationStack`
-- Structuring view models and data flow
-- Optimizing rendering performance for lists and complex layouts
-- Working with environment values and dependency injection in SwiftUI
-
-## State Management
-
-### Property Wrapper Selection
-
-Choose the simplest wrapper that fits:
-
-| Wrapper | Use Case |
-|---------|----------|
-| `@State` | View-local value types (toggles, form fields, sheet presentation) |
-| `@Binding` | Two-way reference to parent's `@State` |
-| `@Observable` class + `@State` | Owned model with multiple properties |
-| `@Observable` class (no wrapper) | Read-only reference passed from parent |
-| `@Bindable` | Two-way binding to an `@Observable` property |
-| `@Environment` | Shared dependencies injected via `.environment()` |
-
-### @Observable ViewModel
-
-Use `@Observable` (not `ObservableObject`) — it tracks property-level changes so SwiftUI only re-renders views that read the changed property:
-
-```swift
-@Observable
-final class ItemListViewModel {
-    private(set) var items: [Item] = []
-    private(set) var isLoading = false
-    var searchText = ""
-
-    private let repository: any ItemRepository
-
-    init(repository: any ItemRepository = DefaultItemRepository()) {
-        self.repository = repository
-    }
-
-    func load() async {
-        isLoading = true
-        defer { isLoading = false }
-        items = (try? await repository.fetchAll()) ?? []
-    }
-}
-```
-
-### View Consuming the ViewModel
-
-```swift
-struct ItemListView: View {
-    @State private var viewModel: ItemListViewModel
-
-    init(viewModel: ItemListViewModel = ItemListViewModel()) {
-        _viewModel = State(initialValue: viewModel)
-    }
-
-    var body: some View {
-        List(viewModel.items) { item in
-            ItemRow(item: item)
-        }
-        .searchable(text: $viewModel.searchText)
-        .overlay { if viewModel.isLoading { ProgressView() } }
-        .task { await viewModel.load() }
-    }
-}
-```
-
-### Environment Injection
-
-Replace `@EnvironmentObject` with `@Environment`:
-
-```swift
-// Inject
-ContentView()
-    .environment(authManager)
-
-// Consume
-struct ProfileView: View {
-    @Environment(AuthManager.self) private var auth
-
-    var body: some View {
-        Text(auth.currentUser?.name ?? "Guest")
-    }
-}
-```
-
-## View Composition
-
-### Extract Subviews to Limit Invalidation
-
-Break views into small, focused structs. When state changes, only the subview reading that state re-renders:
-
-```swift
-struct OrderView: View {
-    @State private var viewModel = OrderViewModel()
-
-    var body: some View {
-        VStack {
-            OrderHeader(title: viewModel.title)
-            OrderItemList(items: viewModel.items)
-            OrderTotal(total: viewModel.total)
-        }
-    }
-}
-```
-
-### ViewModifier for Reusable Styling
-
-```swift
-struct CardModifier: ViewModifier {
-    func body(content: Content) -> some View {
-        content
-            .padding()
-            .background(.regularMaterial)
-            .clipShape(RoundedRectangle(cornerRadius: 12))
-    }
-}
-
-extension View {
-    func cardStyle() -> some View {
-        modifier(CardModifier())
-    }
-}
-```
-
-## Navigation
-
-### Type-Safe NavigationStack
-
-Use `NavigationStack` with `NavigationPath` for programmatic, type-safe routing:
-
-```swift
-@Observable
-final class Router {
-    var path = NavigationPath()
-
-    func navigate(to destination: Destination) {
-        path.append(destination)
-    }
-
-    func popToRoot() {
-        path = NavigationPath()
-    }
-}
-
-enum Destination: Hashable {
-    case detail(Item.ID)
-    case settings
-    case profile(User.ID)
-}
-
-struct RootView: View {
-    @State private var router = Router()
-
-    var body: some View {
-        NavigationStack(path: $router.path) {
-            HomeView()
-                .navigationDestination(for: Destination.self) { dest in
-                    switch dest {
-                    case .detail(let id): ItemDetailView(itemID: id)
-                    case .settings: SettingsView()
-                    case .profile(let id): ProfileView(userID: id)
-                    }
-                }
-        }
-        .environment(router)
-    }
-}
-```
-
-## Performance
-
-### Use Lazy Containers for Large Collections
-
-`LazyVStack` and `LazyHStack` create views only when visible:
-
-```swift
-ScrollView {
-    LazyVStack(spacing: 8) {
-        ForEach(items) { item in
-            ItemRow(item: item)
-        }
-    }
-}
-```
-
-### Stable Identifiers
-
-Always use stable, unique IDs in `ForEach` — avoid using array indices:
-
-```swift
-// Use Identifiable conformance or explicit id
-ForEach(items, id: \.stableID) { item in
-    ItemRow(item: item)
-}
-```
-
-### Avoid Expensive Work in body
-
-- Never perform I/O, network calls, or heavy computation inside `body`
-- Use `.task {}` for async work — it cancels automatically when the view disappears
-- Use `.sensoryFeedback()` and `.geometryGroup()` sparingly in scroll views
-- Minimize `.shadow()`, `.blur()`, and `.mask()` in lists — they trigger offscreen rendering
-
-### Equatable Conformance
-
-For views with expensive bodies, conform to `Equatable` to skip unnecessary re-renders:
-
-```swift
-struct ExpensiveChartView: View, Equatable {
-    let dataPoints: [DataPoint] // DataPoint must conform to Equatable
-
-    static func == (lhs: Self, rhs: Self) -> Bool {
-        lhs.dataPoints == rhs.dataPoints
-    }
-
-    var body: some View {
-        // Complex chart rendering
-    }
-}
-```
-
-## Previews
-
-Use `#Preview` macro with inline mock data for fast iteration:
-
-```swift
-#Preview("Empty state") {
-    ItemListView(viewModel: ItemListViewModel(repository: EmptyMockRepository()))
-}
-
-#Preview("Loaded") {
-    ItemListView(viewModel: ItemListViewModel(repository: PopulatedMockRepository()))
-}
-```
-
-## Anti-Patterns to Avoid
-
-- Using `ObservableObject` / `@Published` / `@StateObject` / `@EnvironmentObject` in new code — migrate to `@Observable`
-- Putting async work directly in `body` or `init` — use `.task {}` or explicit load methods
-- Creating view models as `@State` inside child views that don't own the data — pass from parent instead
-- Using `AnyView` type erasure — prefer `@ViewBuilder` or `Group` for conditional views
-- Ignoring `Sendable` requirements when passing data to/from actors
-
-## References
-
-See skill: `swift-actor-persistence` for actor-based persistence patterns.
-See skill: `swift-protocol-di-testing` for protocol-based DI and testing with Swift Testing.